Creating custom property types

Properties provide the means to specify and examine the state, appearance, and behavior of nodes. For example, a property can define a color, indicate whether a button is pressed, or specify the alignment of an item.

Properties provide a uniform way to access data of Kanzi nodes, so that many Kanzi subsystems can manipulate the data. That way you can, for example, animate property values, provide bindings between property values, and monitor property value changes.

Each property is described by a property type. The property type uniquely describes the property where it is used, the name and the type of values the property holds. The data type defines the type of the data of the property.

Note that animations can only animate floating point numbers. So, to animate properties that have more than one value (for example, color and transformation), you can split the property data into a set of floating point property data attributes (for example, the RGBA channels in a color property type).

Setting and using namespaces for custom property types

The names of custom property types must be unique in a Kanzi application. When your Kanzi application uses .kzb files exported from different Kanzi Studio projects, to ensure that the names of custom property types remain unique within that application, use in each .kzb file a different namespace for custom property types.

When you create property types in Kanzi Engine plugins, use unique names across all plugins and Kanzi Studio projects you use in the same Kanzi application.

In Kanzi you can use these names to access a property type in your application:

• Namespace.Name to access the property type using the Kanzi Engine API.
  For example, to access in the Gauges .kzb namespace a property type named Speed, use Gauges.Speed.
• Name to access the property type in shaders.
  For example, SpeedNeedleColor.
• Display Name is a user-friendly name that you can see in the Library > Property Types.
  For example, Speed Needle Color

To set the namespace for all custom property types in a Kanzi Studio project, in Kanzi Studio in the main menu select Project > Properties and set the Property Namespace property to the namespace you want to use for all custom property types in this project:

• Manually enter the namespace you want to use for the custom property types in this project.
• Click Macro and select <ProjectName> to use the name of the Kanzi Studio project as the namespace for custom property types in this project. If a project name contains a space, the namespace uses underscore instead of the space.
  For example, if the name of the project is Primary gauges, the property type namespace is primary_gauges. For a property named Speed in that project, the full name of the property is primary_gauges.Speed.

Creating a custom property

To create a custom property:

1. In the Library press Alt and right-click Property Types and select Property Type.
   
   The Property Type Editor opens.
2. In the Property Type Editor set:
   • In the Naming category set:
     
     • Name to the name for the property type when you use it in the Kanzi API. This name cannot contain spaces.
     • Display Name to the name for the property type when you use it in Kanzi Studio.
       <Name> sets the Display Name property to the same value as the Name property. This is the default value.
     • Runtime Name shows the name of the property type that Kanzi Studio exports.
       This is the name which you can use to access this property type in the exported .kzb file. The Runtime Name is a combination of the Property Namespace property set in the Project > Properties and the Name property of this property type.
     • Category to the category in which Kanzi Studio shows your property type in the Properties and Add Properties windows.
       Use Category to quickly find your properties in Kanzi Studio.
   • In the Type category define the type of your property which determines what kind of data it holds. You can use one of these data types:
     • Boolean stores values True or False and has no type-specific properties.
     • Color stores color information for red, green, blue, and alpha channels (RGBA).
       Note that even though in Kanzi Studio you can set color values for hue, saturation, light, and alpha channels (HSLA), Kanzi stores them in RGBA. This means you can animate only RGBA values.
     • Enumeration stores a set of key value pairs, so that each unique key resolves to a unique integer.
     • Float stores single precision floating point values.
     • Integer stores 32-bit signed integer values.
     • Matrix 3x3 stores 3x3 matrices of floating point numbers, which you can use to store transformations for 2D nodes.
     • Matrix 4x4 stores 4x4 matrices of floating point numbers, which you can use to store transformations for 3D nodes.
     • Message represents messages, which you can use to add message triggers for application event messages. See Using messages.
     • Project Item stores references to objects and does not have type-specific properties. You can use Project item data type only in application code, for which Kanzi converted the property into the path of the target in a string format.
     • Property Type stores references to other property types. You can use Property type data types only in application code, for which Kanzi converts the property into the name of the target in a string format.
     • Text stores plain text and does not have type-specific properties.
     • Vector 2D stores vectors of two floating point numbers.
     • Vector 3D stores vectors of three floating point numbers.
     • Vector 4D stores vectors of four floating point numbers.
   • In the Type Specific category you can set the lower and upper value limits for your property, and, if you are using a slider editor for the property, you can set the value for the slider step.
   • In the Value section you can set the default value and sorting index for your property.
3. Click Save.
   You can now add and use the property you created just like any other property in Kanzi.

See also

Property system

Property types

Open topic with navigation